While all this toolchain talk is in the air ...
We've got several major activities going on that are relying upon our current-and-working toolchain:
* Release notes need to build properly by 16 March[1] * Updates to existing guides (IG, SMG) by mid-March[2] * New guides going into Beta in March (DUG, AG)
Beyond being confident the guides can build cleanly, which Jared has demonstrated in the one case, we need to know that they can match whatever MUST list we put together. Some SHOULD items are OK, too.
For starters:
* Must be possible to go from Wiki to usable XML with similar process/hassle as current pathway
* Must be able to pull book from CVS and build in Fedora 8 and Fedora 9 tests (Alpha, Beta, RC, Sulphur) - follows the tradition of not requiring docs tools to work for Fedora N-1
* Should be able to build in Fedora 7
* Must produce PO files that are line-for-line identical to the one produced in the last version - this is to minimize re-translation or having to re-check already translated strings on content that is already translated (IG, Relnotes)
* Must process PO and POT so as to not put a burden on translation and Transifex (line-for-line identical or close enough)
* Must be usable by Release Engineering in composing the build
* Must be hostable by Fedora Infrastructure for Docs, L10n, or RelEng build systems
* Must have a reliable upstream, should be relied upon for at least 12 months
* Must have a packager who affirms to maintain the package, should be affirmed for at least 12 months
* Should build RPMs that match the RPM capability of /cvs/docs - need to list these out
Anything else?
- Karsten
[1] http://fedoraproject.org/wiki/DocsProject/Schedule [2] Jared has the SMG building in publican but we haven't run it against any kind of checklist for completion
Karsten 'quaid' Wade wrote:
While all this toolchain talk is in the air ...
We've got several major activities going on that are relying upon our current-and-working toolchain:
- Release notes need to build properly by 16 March[1]
- Updates to existing guides (IG, SMG) by mid-March[2]
- New guides going into Beta in March (DUG, AG)
Beyond being confident the guides can build cleanly, which Jared has demonstrated in the one case, we need to know that they can match whatever MUST list we put together. Some SHOULD items are OK, too.
For starters:
- Must be possible to go from Wiki to usable XML with similar
process/hassle as current pathway
- Must be able to pull book from CVS and build in Fedora 8 and Fedora 9
tests (Alpha, Beta, RC, Sulphur)
- follows the tradition of not requiring docs tools to work for Fedora
N-1
Should be able to build in Fedora 7
Must produce PO files that are line-for-line identical to the one
produced in the last version
- this is to minimize re-translation or having to re-check already
translated strings on content that is already translated (IG, Relnotes)
- Must process PO and POT so as to not put a burden on translation and
Transifex (line-for-line identical or close enough)
Must be usable by Release Engineering in composing the build
Must be hostable by Fedora Infrastructure for Docs, L10n, or RelEng
build systems
- Must have a reliable upstream, should be relied upon for at least 12
months
- Must have a packager who affirms to maintain the package, should be
affirmed for at least 12 months
- Should build RPMs that match the RPM capability of /cvs/docs
- need to list these out
Anything else?
- Karsten
[1] http://fedoraproject.org/wiki/DocsProject/Schedule [2] Jared has the SMG building in publican but we haven't run it against any kind of checklist for completion
I would love to be able to transfer to xml as in know how to transfer to xml so I can actually work on the DuG. It's at the stage were it is edit ready so the reason why there hasn't been any discussion is because I have no idea of how to proceed from now.
I'm not trying to steal this post btw it just links in :)
Cheers,
Marc
On Thu, 2008-02-21 at 17:30 -0800, Karsten 'quaid' Wade wrote:
While all this toolchain talk is in the air ...
We've got several major activities going on that are relying upon our current-and-working toolchain:
Just to be clear... I'm *not* pushing for a change to a new toolchain before F9. I think it would be awfully rash of us to do so at this point in the game.
I also don't want anybody to mistake my enthusiasm for publican as somehow knocking the current tool chain. I'll be the first to admit that I don't know the current tool chain very well. Additionally, I don't think we've tested publican enough (as far as the translations go, especially) to know whether or not it's a good fit for what we do. What I *am* enthusiastic about is how quickly publican allows people to hit the ground running, especially those who are new to DocBook and their tool chains.
If I had to prognosticate at this point, I'd say that in two years' time, we'll have taken the best pieces of publican and the current tool chain and welded them together.
-Jared
On Fri, 2008-02-22 at 18:57 +0900, Marc Wiriadisastra wrote:
I would love to be able to transfer to xml as in know how to transfer to xml so I can actually work on the DuG. It's at the stage were it is edit ready so the reason why there hasn't been any discussion is because I have no idea of how to proceed from now.
I'd be happy to help people transition docs from the Wiki to XML. But before I do another doc, I'd really like some feedback from the more experienced people on the team on the job I did with the Software Management Guide. Was everybody OK with the translation from wiki markup to DocBook? Is there something I missed? Please give me feedback!
-Jared
On Fri, 2008-02-22 at 10:40 -0500, Jared Smith wrote:
On Fri, 2008-02-22 at 18:57 +0900, Marc Wiriadisastra wrote:
I would love to be able to transfer to xml as in know how to transfer to xml so I can actually work on the DuG. It's at the stage were it is edit ready so the reason why there hasn't been any discussion is because I have no idea of how to proceed from now.
Likely we should do one Big Edit in the wiki, for style and grammar and such.
Can one of the DuG people make a wiki page with:
Chapter :: Status :: Editor
... then those of us who want to/can edit put your names by some chapters and proceed to edit in the wiki. Edit goals are:
* Wordsmith * Stylesmith * Formatting consistency and choices for XML conversion
I'd be happy to help people transition docs from the Wiki to XML. But before I do another doc, I'd really like some feedback from the more experienced people on the team on the job I did with the Software Management Guide. Was everybody OK with the translation from wiki markup to DocBook? Is there something I missed? Please give me feedback!
Know what I've been waiting for? The CVS module and bugzilla component. Let's commit into CVS, then I can check it out, do edits and comments, and it's all in the record, etc.
- Karsten
On Fri, 2008-02-22 at 14:58 -0800, Karsten 'quaid' Wade wrote:
On Fri, 2008-02-22 at 10:40 -0500, Jared Smith wrote:
On Fri, 2008-02-22 at 18:57 +0900, Marc Wiriadisastra wrote:
I would love to be able to transfer to xml as in know how to transfer to xml so I can actually work on the DuG. It's at the stage were it is edit ready so the reason why there hasn't been any discussion is because I have no idea of how to proceed from now.
Likely we should do one Big Edit in the wiki, for style and grammar and such.
Can one of the DuG people make a wiki page with:
Chapter :: Status :: Editor
... then those of us who want to/can edit put your names by some chapters and proceed to edit in the wiki. Edit goals are:
- Wordsmith
- Stylesmith
- Formatting consistency and choices for XML conversion
Should we just add it to the toc page so that at least it's a central location and linked? If so I can do that later this afternoon.
Is there a place where the style and format consistency is located across the docs?
I would be more than happy to help do that but I will have to pass for the wordsmith since that is my worst talent. I sucked at it in high school.......
Cheers,
Marc
<snip>
On Sat, 2008-02-23 at 08:28 +0900, Marc Wiriadisastra wrote:
On Fri, 2008-02-22 at 14:58 -0800, Karsten 'quaid' Wade wrote:
Chapter :: Status :: Editor
... then those of us who want to/can edit put your names by some chapters and proceed to edit in the wiki. Edit goals are:
- Wordsmith
- Stylesmith
- Formatting consistency and choices for XML conversion
Should we just add it to the toc page so that at least it's a central location and linked? If so I can do that later this afternoon.
Sure; I just want to be able to clearly take responsibility for a part of it, and then I can do it. :)
Is there a place where the style and format consistency is located across the docs?
http://fedoraproject.org/wiki/DocsProject/StyleGuide http://fedoraproject.org/wiki/DocsProject/WritingUsingTheWiki http://fedoraproject.org/wiki/WikiEditing#Marking_Technical_Terms http://fedoraproject.org/wiki/WikiEditing#Writing_Example_Commands
This can all be derived from this workflow:
http://fedoraproject.org/wiki/DocsProject/WorkFlow#WikiPublicationMethodforF...
I would be more than happy to help do that but I will have to pass for the wordsmith since that is my worst talent. I sucked at it in high school.......
Happy to do that part, I'm a fair editor; at least I'm consistent. :)
- Karsten, Editor-in-Chief of his HS newspaper
On Fri, 2008-02-22 at 10:34 -0500, Jared Smith wrote:
On Thu, 2008-02-21 at 17:30 -0800, Karsten 'quaid' Wade wrote:
While all this toolchain talk is in the air ...
We've got several major activities going on that are relying upon our current-and-working toolchain:
Just to be clear... I'm *not* pushing for a change to a new toolchain before F9. I think it would be awfully rash of us to do so at this point in the game.
I also don't want anybody to mistake my enthusiasm for publican as somehow knocking the current tool chain. I'll be the first to admit that I don't know the current tool chain very well. Additionally, I don't think we've tested publican enough (as far as the translations go, especially) to know whether or not it's a good fit for what we do. What I *am* enthusiastic about is how quickly publican allows people to hit the ground running, especially those who are new to DocBook and their tool chains.
Clearly, the interest in publican and it's (apparent) ease to get started with an XML book is a feature we've been missing in the Fedora Docs toolchain.
Honestly, though, we have been pursuing the higher gain. Across open source projects, the wiki is where the developers and other contributors do their community documentation. When we focused exclusively on XML, we had very interested or enabled contributors.
Some years back I spoke with the Mozilla Dev documentation folks, who had then changed from DocBook XML to a fully wiki-based system:
http://developer.mozilla.org/en/docs/Main_Page
Switching to the wiki, they saw 10x increase from developers, even the ones who knew DocBook well enough. In addition, many new contributors came in to help, which increased the editorial and content group.
It's unclear to me how much these features of publican matter to Fedora Docs. For example, the people who have dropped by #fedora-docs looking for publican help seem to be working on their own content. While maintaining tools that allow the creation of free content is a part of the Docs charter, it's definitely a lower priority than enabling Fedora contributors to create content for Fedora. Right now that means helping to maintain the wiki:
http://fedoraproject.org/wiki/DocsProject/WikiGardening
If I had to prognosticate at this point, I'd say that in two years' time, we'll have taken the best pieces of publican and the current tool chain and welded them together.
An open community development from this point forward is definitely to be desired.
- Karsten
On Sat, 2008-02-23 at 01:15 -0800, Karsten 'quaid' Wade wrote:
On Sat, 2008-02-23 at 08:28 +0900, Marc Wiriadisastra wrote:
On Fri, 2008-02-22 at 14:58 -0800, Karsten 'quaid' Wade wrote:
Chapter :: Status :: Editor
... then those of us who want to/can edit put your names by some chapters and proceed to edit in the wiki. Edit goals are:
- Wordsmith
- Stylesmith
- Formatting consistency and choices for XML conversion
Should we just add it to the toc page so that at least it's a central location and linked? If so I can do that later this afternoon.
Sure; I just want to be able to clearly take responsibility for a part of it, and then I can do it. :)
Is there a place where the style and format consistency is located across the docs?
http://fedoraproject.org/wiki/DocsProject/StyleGuide http://fedoraproject.org/wiki/DocsProject/WritingUsingTheWiki http://fedoraproject.org/wiki/WikiEditing#Marking_Technical_Terms http://fedoraproject.org/wiki/WikiEditing#Writing_Example_Commands
This can all be derived from this workflow:
http://fedoraproject.org/wiki/DocsProject/WorkFlow#WikiPublicationMethodforF...
I would be more than happy to help do that but I will have to pass for the wordsmith since that is my worst talent. I sucked at it in high school.......
Happy to do that part, I'm a fair editor; at least I'm consistent. :)
- Karsten, Editor-in-Chief of his HS newspaper
Done the layout.
http://fedoraproject.org/wiki/Docs/Drafts/DesktopUserGuide#preview
I'll start labeling the sections when I get home from work. I'll also start editing the sections if anyone else wants to start go for it. Table format seems to be the neatest.
Cheers,
Marc
On Sat, 2008-02-23 at 01:15 -0800, Karsten 'quaid' Wade wrote:
On Sat, 2008-02-23 at 08:28 +0900, Marc Wiriadisastra wrote:
On Fri, 2008-02-22 at 14:58 -0800, Karsten 'quaid' Wade wrote:
Chapter :: Status :: Editor
... then those of us who want to/can edit put your names by some chapters and proceed to edit in the wiki. Edit goals are:
- Wordsmith
- Stylesmith
- Formatting consistency and choices for XML conversion
Should we just add it to the toc page so that at least it's a central location and linked? If so I can do that later this afternoon.
Sure; I just want to be able to clearly take responsibility for a part of it, and then I can do it. :)
Is there a place where the style and format consistency is located across the docs?
http://fedoraproject.org/wiki/DocsProject/StyleGuide http://fedoraproject.org/wiki/DocsProject/WritingUsingTheWiki http://fedoraproject.org/wiki/WikiEditing#Marking_Technical_Terms http://fedoraproject.org/wiki/WikiEditing#Writing_Example_Commands
This can all be derived from this workflow:
http://fedoraproject.org/wiki/DocsProject/WorkFlow#WikiPublicationMethodforF...
I would be more than happy to help do that but I will have to pass for the wordsmith since that is my worst talent. I sucked at it in high school.......
Happy to do that part, I'm a fair editor; at least I'm consistent. :)
- Karsten, Editor-in-Chief of his HS newspaper
I've edited a few sections. I'll work on it some more.
Cheers,
Marc
docs@lists.stg.fedoraproject.org
-
Jared Smith -
Karsten Wade -
Marc Wiriadisastra