View Issue Details
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0005120||GNUnet||documentation||public||2017-08-18 14:29||2019-02-12 08:46|
|Priority||high||Severity||text||Reproducibility||have not tried|
|Product Version||SVN HEAD|
|Target Version||0.11.1||Fixed in Version|
|Summary||0005120: Update the documentation|
|Description||We have exported the documentation from Drupal to TeXinfo.|
This project has been merged into gnunet.git/doc/, now we need to update its content.
Obviously this is not a task I can assign to a single person, so we need to cooperate on this one.
My idea is that everyone reads the documentation and fixes its content, one tiny step at a time already helps.
The only real blocker are the chapters "installation", "philosophy", and "user".
Developers will most likely just work with HEAD or at least once in a while generate the documentation.
I'd even go as far as moving this to the next version (the version AFTER the next version). It would be nice to have, but it's not really required for the next version to be usable.
I'll do some work on this ticket, but I can not finish it by myself because I need to focus on other tasks.
How much of the content (as in, text not the code that produces the output text) do we need to update to call it release candidate compatible / worthy of quality?
It's already better than pointing to Drupal.
Update on this task from my side:
I'm still focused cleaning up what we have (probably almost done, it's basically just the build system now + last non-fatal errors in texinfo), the corrections ("update") have not been my priority tasks so far.
||Just brief update: this is on my todo list.|
If you work on this, could you use the version in the doc/documentation branch, or should I regulary merge this into master?
Maintaining this in a branch is not really useful, I (rarely) break anyones workflow, but when I do it is caught by an CI. So it's a 50/50 chance of breaking something because you can't cover all corner cases on your local machine.
There's also the question how much should go into the next release.
I've planned out the Documentation work without an end. It's complete when I can get a sample group of people and they all understand at least the introduction, at least the installation, usage and optionally the first parts of the the developer handbook (this is targeted at developers, but even developer struggle with what we have at this moment).
Please just regularly merge everything into master, or even just work on master directly for this stuff. It's not like the docs not building would cause a major issue for anyone, and it's more important that people do see the work and/or report if there are issues that don't happen on your system back to you.
I usually only branch for really major changes that are _expected_ to break things badly for people. For everything else, it's Git, so if Git head is unexpectedly broken, one can always checkout an earlier version ;-).
> It's not like the docs not building would cause a major issue for anyone, and it's more important that people do see the work and/or report if there are issues that don't happen on your system back to you.
Well when the texinfo syntax is wrong, they do cause build failures.
Another thing I should have a (local) test for, other than for experience, knowledge and emacs + manual rendering complaining.
> I usually only branch for really major changes that are _expected_ to break things badly for people. For everything else, it's Git, so if Git head is unexpectedly broken, one can always checkout an earlier version ;-).
I think this is not really good as long as we don't have enough tests or a good CI. With a Continous Deployment with commits only being merged after they pass a certain amount of tests it would be okay.
But to assume master to be broken anyway is not really good. Of course we can settle on "it's broken by default" for now, but I'd like to change this in the future once enough mechanisms are in place to catch the broken.
||We've got teams working on philo, installation and user chapters now ;-)|
|2017-08-18 14:29||ng0||New Issue|
|2017-08-18 14:31||ng0||Note Added: 0012378|
|2017-08-21 09:40||ng0||Note Added: 0012384|
|2017-08-21 09:41||ng0||Note Edited: 0012384||View Revisions|
|2017-08-22 16:26||Christian Grothoff||Priority||normal => high|
|2017-08-22 16:26||Christian Grothoff||Severity||minor => text|
|2017-08-22 16:26||Christian Grothoff||Status||new => confirmed|
|2017-08-22 16:26||Christian Grothoff||Product Version||=> SVN HEAD|
|2017-09-26 20:13||ng0||Note Added: 0012439|
|2017-09-26 20:13||ng0||Assigned To||=> Christian Grothoff|
|2017-09-26 20:13||ng0||Status||confirmed => feedback|
|2017-09-27 20:20||ng0||Relationship added||child of 0005141|
|2017-09-27 20:25||ng0||Relationship added||parent of 0005126|
|2017-09-27 20:26||ng0||Relationship deleted||parent of 0005126|
|2017-10-04 15:23||Christian Grothoff||Note Added: 0012460|
|2017-10-04 15:23||Christian Grothoff||Status||feedback => assigned|
|2017-11-28 14:37||ng0||Note Added: 0012609|
|2017-11-28 14:40||ng0||Note Added: 0012610|
|2017-11-28 20:43||Christian Grothoff||Note Added: 0012611|
|2017-11-28 20:58||ng0||Note Added: 0012612|
|2018-06-27 21:48||Christian Grothoff||Note Added: 0013092|
|2018-06-27 21:49||Christian Grothoff||Assigned To||Christian Grothoff =>|
|2018-06-27 21:49||Christian Grothoff||Status||assigned => closed|
|2018-06-27 21:49||Christian Grothoff||Status||closed => assigned|
|2018-10-30 19:13||ng0||Relationship deleted||child of 0005141|
|2019-01-27 11:10||catonano||Tag Attached: documentation|
|2019-02-12 08:46||Christian Grothoff||Status||assigned => confirmed|
|2019-02-12 08:46||Christian Grothoff||Target Version||0.11.0pre66 => 0.11.1|