Talk:Relation of wiki and manuals

From MEPIS Documentation Wiki

Jump to: navigation, search


Importation discussion

2009 discussion

Excellent work, Hanzl! Bravo! I posted the link on ML and asked for review, I think Marcos at least might look at it next week, and hopefully Adrian as well. Jerry bond 07:53, 6 October 2009 (EDT)

Well, there is rather big proportion of hasty and sloppy programmer's work which should likely be replaced by something more robust. But at least we finally have a realistic framework where pieces can be improved one by one. --Hanzl 08:07, 6 October 2009 (EDT)
Here is that ML thread--Hanzl 09:09, 6 October 2009 (EDT)
Thanks. I emailed Adrian and asked him to look at it, since he had a lot to do with setting up this Wiki and is pretty good at scripts. Jerry bond 09:30, 6 October 2009 (EDT)

2008 discussion

I think that we need to:

  1. import stuff from manual that matches the articles in Wiki (since manual has better info)
  2. implement a formating standard in Wiki that matches the manual, we need to write a manual of style or something for Wiki with clear examples. -- AdrianTM 00:25, 6 February 2008 (EST)
I suggest we run a pilot and see how it goes. Questions: 1) Do you want to do that or shall I? 2) Just copy the html and paste it in? I seem to remember that when I did that last summer as a suggestion, a bunch of people jumped all over me. 3) Should we have a special category such as Manual? 4) Should we maybe use a header such as {{Manual}} that points to the special formatting requirements? 5) (I have more...) Jerry bond 07:19, 6 February 2008 (EST)
Small pilot would be nice. Maybe small 'technical' pilot first (to test technical possibilities of the wiki->manual process) to have some concrete instructions for the 'social pilot' (how editors will react) later. Category Manual would be nice, it makes it technically easier to collect material. Special header may be nice as well - it could link to page with detailed format instructions. But maybe the header could somehow be added automatically to all pages in category Manual? Interested programmers could download (or export) wiki pages, try to convert them into static manual and report which tools seem to be good for this job and which type of wiki formatting is good input for these tools (I will be happy to try this, thought not sooner than a week from now as I will be disconnected few days). I think we should make the formatting as close to normal wiki pages as we can and only introduce specialities where really needed for the specific task of Manual export. At this moment I would just import few pages and experiment with the format a bit. --Hanzl 08:12, 6 February 2008 (EST)
To add to the mix: we now have a PDF of the User's Manual that I am about to post for review on ML. It took a volunteer a lot of time to create it, so it would be highly desireable to automate the process in the future. Jerry bond 08:39, 6 February 2008 (EST)
Then we could consider going from wiki via DocBook to html and pdf, there is strong tradition of Linux docs using these tools. And starting this conversion path from Media Wiki would be welcome by community I think. Thought I would be quite surprised if this was not done before, it is SO obvious need :-) --Hanzl 09:18, 6 February 2008 (EST)
I agree on consolidating everything. Afterwards, we can maintain the wiki as the core of the documentation - it can grow and mature far beyond the scope of a manual, and do so more quickly. Also, at the time of a new Mepis release:
  1. we can add any contributions pertinent to the new release.
  2. the community can preen the wiki and make sure everything works with the new version.
  3. then have our style-checkers tidy things up (periodic revisions would benefit the wiki anyway)
  4. finally, we can export it into an official manual for the new release.--Jay Armstrong 16:05, 6 February 2008 (EST)

2007 discussion

Beginning proposl

  1. There is wiki. There are classical manuals. What should be their relation? This question pops up here and there, and I am not sure we already have good established models to follow.
  2. Acting as a gateway between wiki and classical manual takes human resources. Even with a lot of work devoted to this, manuals will quickly get out of date. But manuals created by a closed team of authors can be more coherent. Wiki will always contain some mess somewhere. We have reasons to like both manuals and wiki, and we can waste a lot of our time trying to keep them (a bit) in sync.
  3. Maybe there are some future, not yet established ways of getting the best of both. Maybe wiki can be like a cvs in software development and manuals like stable releases of software. With rules (on wiki) describing how the 'release' will happen, and maybe computer scripts helping with this. (Maybe we even need 'stable branch' and 'development branch'... Oh no, this would be really hard with wiki.)
  4. Parts of related discussion are in Talk:New User Guide 7. I felt that my related thoughts are too abstract to be of any help for that page, so I created this one.
  5. Parts of this process happened in creation of Mepis 7 Manual. Maybe we should rather refine the process, instead of overloading nice people by synchronization work?
  6. Anybody knows good working model for wiki/manuals, saving dedicated humans from acting as a gateway forever? Is there any computer help?

--Hanzl 15:07, 22 October 2007 (EDT)

  1. What about Category: CD Manual ?

At the 'release time', all pages with this category would become part of the manual on MEPIS CD. Links to other wiki pages would become external links to the live wiki. Nightly script could build the manual to have a snapshot available online in proper style. --Hanzl 15:25, 22 October 2007 (EDT)


Sorry, did not see this earlier--you raise good points that we discussed a lot as we were setting up work for the Manual. The big problem is that Wiki formatted text apparently can not be translated into html except manually, with a lot of format changes. But what you are talking about is a long-term goal for sure, and we would ideally have a seamless process in place along the lines you are describing by MEPIS 8. Jerry bond 12:39, 7 November 2007 (EST)

I think there's a way to convert Wiki2html (this is probably the name of the tool too... I need to search), by the way here is a cool tool that we might need at some point: -- AdrianTM 13:18, 5 February 2008 (EST)
well mounting doesn't work, I will play with that software to see if I can make it work. -- AdrianTM 13:37, 5 February 2008 (EST)
Wow, WikipediaFS looks nice. I always enjoyed the many ways to combine UNIX tools, but this is quite pleasing surprise for me. Yes, it may be a good tool for the job. --Hanzl 13:32, 5 February 2008 (EST)
Here's a wiki2html convertor Didn't try it.-- AdrianTM 13:41, 5 February 2008 (EST)
Actually any wiki page displayed in a browser is HTML, right? Just keep the "body" take out the rest of the rest of the Wiki stuff. For example see the source page of this page, you'll see a "-- start content --" tag. Now if we get that thing to mount we can just copy the Wiki pages, and then cut them automatically and export as HTML. -- AdrianTM 13:43, 5 February 2008 (EST)
Yes, I think we could build quite nice prototype system with just awk/sed/perl/etc. processing html pages got from the web server. Even "wget" might be enough to get pages - just wget Category:CD_Manual with 1-deep recursion and all material is in place. More elegant way to transform pages might be XSLT (but I do not know/use this technology). One slightly complicated thing is resolving which links are Manual internal and which are not, but it can be done. --Hanzl 14:07, 5 February 2008 (EST) I forgot: There is also Special:Export--Hanzl 14:16, 5 February 2008 (EST)
Well, all this is good, but the writing, formatting and general readability of the Wiki is just not up to the level of the Manual. Many authors, many styles, many habits. For this to happen, the whole Wiki would have to be changed. I personally believe that now that we have the Manual, revising it manually would be much easier at this point. I do wonder, however, how we are going to catch all the substantive changes that have occurred since the Manual was frozen now some months ago. If we had an easy system (using "Category:Manual"?) to use consistently, that might work, but I doubt at the moment that such a system would be used by Wiki contributors. Jerry bond 14:12, 5 February 2008 (EST)
There would have to be painful merge of wiki and manual, but the workload could be shared. We might need to copy manual to wiki and then resolve duplicities of wiki pages and wiki-manual pages. Looks more nasty than it seemed to me initially. But I would be quite optimistic about contributors and the new system - once we have clear rules for 'Manual' wiki pages and clear goal, I guess people would stick to rules. --Hanzl 14:26, 5 February 2008 (EST)
And the "many authors, many styles etc." question - Jerry, you did most 'style polishing' work on this wiki and I guess you also did much more of this work with the manual (thanks for both!) - if you could do this once only on the wiki, I guess nobody would disrupt your clean style too much? It might change when factual changes do happen, but these places would need your attention anyway when introducing related changes to the manual, and with the here proposed 'new technology' it would be just edit, not merge. --Hanzl 14:46, 5 February 2008 (EST)
  1. It seems to me that Wiki formatting is quite different from xhtml page formatting. Yes, the Wiki pages are obviously rendered as html in order to display in a browser, but the basic style sheets are very different, so all the markup is also different. The easiest way is probably to just copy text, one paragraph at a time from the browser window, and plop it into the place you want while editing your page in Quanta. I don't have any experience with the wiki2html type utilities, but I'm pretty certain that what comes out the end won't resemble what we have got worked up as our current Manual Style.
  2. I think that Hanzl's idea of having pages categorized in the wiki as "CD-manual" would be a great time-saver when it comes to getting material organized and updated. What we would need to do is set up a wiki page for every Manual subsection, and then as it gets rewritten/reviewed by the wikiworkers, getting it put into Manual Style html drafts can be done easily: a bit at a time.
  3. ----------quote: There would have to be painful merge of wiki and manual, but the workload could be shared. We might need to copy manual to wiki and then resolve duplicities of wiki pages and wiki-manual pages. Looks more nasty than it seemed to me initially. But I would be quite optimistic about contributors and the new system - once we have clear rules for 'Manual' wiki pages and clear goal, I guess people would stick to rules. --Hanzl 14:26, 5 February 2008 (EST)
  4. It need not be too painful [maybe] if we don't attempt to merge them so much; just graft a "Manual" category on and work with that, knowing it's destiny. Any wiki pages so written can still link to any other appropriate wiki pages that may not necessarily be Manual cat. pages, right? That is the great thing about the Wiki, is the easy of linking related topics just by adding additional categories at the bottom. -- SilverBear 19:39, 7 February 2008 (EST)
Personal tools