2018-11-21 05:27 CET

View Issue Details Jump to Notes ]
IDProjectCategoryView StatusLast Update
0005120GNUnetdocumentationpublic2018-10-30 19:13
Reporterng0 
Assigned To 
PriorityhighSeveritytextReproducibilityhave not tried
StatusassignedResolutionopen 
Product VersionSVN HEAD 
Target Version0.11.0pre66Fixed in Version 
Summary0005120: Update the documentation
DescriptionWe have exported the documentation from Drupal to TeXinfo.
This project has been merged into gnunet.git/doc/, now we need to update its content.
TagsNo tags attached.
Attached Files

-Relationships Relation Graph ] Dependency Graph ]
+Relationships

-Notes

~0012378

ng0 (developer)

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.

~0012384

ng0 (developer)

Last edited: 2017-08-21 09:41

View 2 revisions

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.

~0012439

ng0 (developer)

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.

~0012460

Christian Grothoff (manager)

Just brief update: this is on my todo list.

~0012609

ng0 (developer)

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.

~0012610

ng0 (developer)

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).

~0012611

Christian Grothoff (manager)

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 ;-).

~0012612

ng0 (developer)

> 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.

~0013092

Christian Grothoff (manager)

We've got teams working on philo, installation and user chapters now ;-)
+Notes

-Issue History
Date Modified Username Field Change
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
+Issue History