On Tue, Apr 25, 2023 at 7:38 PM Nathan Hartman wrote: > On Tue, Apr 25, 2023 at 1:10 PM Tomek CEDRO wrote: > > (..) > > After some consideration a "safer" approach may be more desirable for now: > > > > 1. Migrate all documentation to a separate Documentation/ as it is > > currently done, so we do not lose any content from > > MediaWiki/README/CWIKI, we can add additional content that we need, > > the documentation form is shaped to a satisfactory state, automation > > is verified, nice references, tables of contents, sections, etc. > > People will have solid documentation all the time and we cause no mess > > and we can see how the work on doc goes in reality :-) > > > Suggestion: The "separate" Documentation could be simply an "Unfinished" or > "WorkInProgress" subdirectory inside Documentation. Just dump everything in > there as quickly as possible and then gradually fixup and move sections to > the right places.
Yes, having this kind archive would be cool. As for now I do not know where are the archived documents and so I would mostly focus on simple formatting fixes of the current documentation, while more important things are still waiting to show up in the documentation :-) Then we could move small parts piece by piece into the rst Documentation from a single place, this way we could clearly see what had been done and what is still left todo, but I prefer that Gurus decide on this one :-) > And then this: > > 2. When we have a well shaped "separate" documentation then it may be > > the time to consider merging it with the source code, but not before, > > if desired at all? > > doesn't require moving things from some other system into git. It will just > become a rename within the repo. > What do you think? In future, when the documentation migration is ready, comments/remarks put directly in the source code with Sphinx formatting could only contain that specific file descriptions, nothing more, and then could be gathered all together and attached to the Handbook in a form of a dedicated section API Reference or similar attached to the "general" documentation from the Documentation/ directory. So the final HTML/PDF would contain "general" documentation (from the Documentation/) and the "technical meat" (from all of the src/). I don't know how to do it at this time but I saw this possible (i.e. Kivy) :-) > I like the idea of keeping documentation in sync with the code(as much as > possible given our volunteer-based project). I can see now that merging the documentation itself is quite of a challenge, so documenting the source code itself probably should be left as future task. Small measurable steps towards big dreams :-) > At the very least, documentation will be included in our release artifacts, > so people will have docs "offline" when they download releases. I think > that's a good thing. Thank you Nathan, I also like the release-x.y.tar.gz and release-x.y.pdf approach, maybe we can make it happen :-) :-) > Regarding the CWIKI, suppose we want to document something in particular. > The CWIKI can be a good place for several people to put it together with > realtime collaboration without having to deal with GitHub PRs and whatever, > and when it gets close to ready, it can be migrated into Documentation. > This is what we've been doing with the Release Notes and it seems to work > well. Exactly, as access to wiki is restricted to PMC members (?) I think only organization stuff should be put there, like notes, remarks, scratchpads, task list, maybe some roadmap, and then, when necessary, moved to documentation, I also work that way :-) -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
