[Build-common-hackers] Bug#649151: Bug#649151: cdbs: documentation missing

[Jonas Smedegaard]

Hi Jonathan,

On 12-05-25 at 11:27pm, Jonathan Nieder wrote:
> Jonas Smedegaard wrote:
> 
> > My idea is to...
> >
> >  1. Convert the official documentation to (Pandoc flavor of) 
> >     Markdown
> >  2. Convert and merge in the unofficial documentation
> >  3. Convert translations of unofficial documentation using po4a
> >  4. Update with recent changes to CDBS
> >  5. Release as a separate cdbs-doc source package
> >
> > I don't know how fast this can be done.  I disagree about the 
> > severity of this bugreport, just annoyed by the bug-pingpong.  I may 
> > downgrade it if it stalls too much other more important changes from 
> > entering testing.
> 
> I just noticed this bug in the context of general RC bugfixing, but it 
> has affected me before so I can understand where Steve was coming 
> from. (If it were me, I'd treat it as important, not serious, though.)

I agree, Jonathan, that lack of documentation is not so severe an issue 
that Debian would be better off released without CDBS.  I merely had no 
desire to play severity ping-pong or argue with Steve (see bug#652945).

Feel free to lower severity!


> What documentation do you recommend
> 
>  (1) that someone new to cdbs start with
>  (2) that someone familiar with cdbs use as a reference
> 
> ?  For simplicity, I think it would be fine to render it as plain text
> and treat that as the canonical form in the short term, for example.

I suspect the real question is: What would be a minimal documentation 
satisfying those who dislikes CDBS?

I do not have the answer to that question.

That underlying issue apart, contributions to documentation is much 
appreciated - both aimed at newcomers and existing users, and both 
editing old pieces and writing new stuff from scratch.

Even contributions that perhaps is deemed unsuitable (e.g. because it 
tells a bad tale about CDBS being a great way to skip understanding the 
essentials of packaging) it is still appreciated: it helps provoke 
writing something better.


 - Jonas

-- 
 * Jonas Smedegaard - idealist & Internet-arkitekt
 * Tlf.: +45 40843136  Website: http://dr.jones.dk/

 [x] quote me freely  [ ] ask before reusing  [ ] keep private
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.alioth.debian.org/pipermail/build-common-hackers/attachments/20120526/7ecd73aa/attachment.pgp>