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

[Matias Fonzo]

El 2020-09-25 08:05, Michael Siegel escribió:
> 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.

For Qi I use the version number and the latest update date.

We can probably do the same, since we will be updating often, and if a 
new version comes out, then increase the version and date.

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

Good idea.  If we save the previous version that contains the last 
update made, it would be fine.  Revisions, all the changes will be 
available through git, anyway.

I also don't think this is a super priority (in make releases of the 
handbook and save it) since the manual needs a lot of love.  :-)

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

True, no.  I was just trying to put things out of my mind, it won't be 
necessary to make separate directories.

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

Okidoki.  :-)