Re: [Dragora-members] Dragora Handbook: Structural draft

[Michael Siegel]

Am 24.09.20 um 22:47 schrieb Matias Fonzo:
[...]
> El 2020-09-23 08:35, Michael Siegel escribió:
>> Am 22.09.20 um 21:20 schrieb Matias Fonzo:
>>> El 2020-09-18 19:24, Michael Siegel escribió:
>>
>>> [..]
>>
>> I've thought about two aspects of the Handbook template a bit more:
>>
>>>> The Dragora GNU/Linux-Libre [MAJOR VERSION].x.y Handbook
>>
>> I'm not sure if using [MAJOR VERSION].x.y really goes together with
>> semantic versioning. I guess it doesn't because a change in the minor
>> version number (x) could mean that additional features are introduced
>> (as long as they don't break backwards compatibility). The only thing in
>> that version number that would never affect the Handbook's content would
>> be a changing patch level (y).
>>
>> So, it would, I think, make sense to say
>>
>>   [MAJOR VERSION].[MINOR VERSION]
>>
>> and leave out the patch level completely.
> 
> Yes, the patch level is redundant.  We could start by using the number 3
> for the major version to reflect the series on which the manual is
> based, or add in a general way in the manual description that this
> covers or focuses for Dragora's series 3.

I think it would probably make sense then to have a new Handbook release
whenever Dragora's minor version number changes because incrementing the
minor version number would imply changes that need to be reflected in
the Handbook's content.

A new Hanbook release would then always start at "Revision 0". So, if
Revision 5 was the last revision of the Dragora 3.0 Hanbook, that would
then be followed by the 3.1 Handbook, starting at "Revision 0" again.

Revision numbers are there to indicate changes to the Handbook for an
existing release, e.g., clarifications or corrections of mistakes.

We shouldn't say "Revision 0", though, because that's illogical. Maybe
something like "Initial release" would be better.

Also, we need to think about keeping older Handbook releases around, but
not old revisions of those releases. I wouldn't keep around old revsions
in general, even for the current Handbook.

[...]

> About the structure for the handbook:
> 
> The idea that I have in my head at the moment would be the following,
> the one that I transmit to you.  We would create a directory for each
> language, and a global Makefile (simple) for everything.
> 
> The main manual will contain the nodes exposed by Michael, plus the code
> to include other manuals generated in Dragora, for example the Qi, this
> same I have to see how to fit it or assemble it so that it can be
> included[1], this way it will allow us to maintain separate manuals and
> then join them (surely we have to copy them by hand) to produce the main
> handbook/manual.
> 

Would it really be necessary to keep separate manuals around? I mean, if
everything is simply in the Handbook, then we don't need to do that, I
think. That would also make maintenance easier.

> For now, I can request a new repo, what description would we use?

I'd suggest this:

Repository name: dragora-handbook
Description: The Dragora GNU/Linux-Libre Handbook


--Michael