[katello-devel] Proposal - replace current wiki with YARD and Github-wiki

[Petr Chalupa]

Thanks for the input. Now I see I was not that clear about motivation 
behind it. I'll try to answer your concerns.

## General comments:

I want to drop the wiki because I do not want to have too many 
tools/places to look for information. I think we need Yard anyway so I 
want to move there with the exception of rapidly changing design 
documents (move them to Github wiki, after they are finished move them 
to Yard docuemntation).

I think that having docs and code close together does matter. Code 
documentation is right in the code and its the first place where Ruby 
developer are looking for information. If the information lies somewhere 
on wiki and nobody is reading it, that is not a good thing. I know we 
could try to build better habits, but that would be hard. Moving 
information to place (the source code) which is read by every developer 
sound better to me.

Currently there are some guides for development on wiki about how to 
write e.g. TwoPane. I think It would be better not to write these guides 
but to organize this e.g. TwoPane as a library and document the library 
with Yard. Some general description and examples would be associated 
with TwoPane module which would also be namespace for all TwoPane 
related code.

This approach also encourages good code organization. You need a module 
to associate the documentation so the related code is then naturally 
placed inside the module.

On 20.11.12 9:48, Lukas Zapletal wrote:
> It seems nobody is having objections, so let me raise mine :-)
>
>> - as a Katello user be able to access Katello documentation
>> - as a developer be able to edit documentation with code
>>    - get Katello documentation closer to the code
>>    - get Katello documentation to be part of pull-requests
>> - as a developer be able to see my documentation changes easily
>> without lengthy documentation generation
>> - as a developer be able to access up-to-date documentation
>> - as a developer be able to create and share design documents easily
>> without ties to code
>>
>
> How many of these come from real demand? You mention things that are
> obvious to me. Frankly, the only one valid requirement I see is:
>
>>    - get Katello documentation to be part of pull-requests
>
> Yeah, I like this, but I find the rest obvious. To me, this is the only
> one advantage you propose. All the other things are just about how much
> effort we are gonna give into (any) documentation solution. The
> sentences you wrote are tools-transparent.

You are right I could do a better job in describing my motivation for 
this. I've tried again in General comments at the top.

>> Convert whole wiki to markdown files [6]. Split pages to design
>> pages and documentation. Place documentation using Yard to Katello
>> repository and design pages to Katello wiki on Github. Drop current
>> wiki completely.
>
> Conversion is a painful process, you will be working on this for maybe
> days and I only see the one added value (pull-requests). I don't think
> it worths it.

Pull-requests are not the only added value, see at the top. I agree it 
will be painful, but should be done. My feeling right now is that our 
wiki is so outdated that people rather ask before going there, which 
introduces space for error. IMO Wiki should be cleaned up anyway 
regardless of how this discussion end.

>> - Github wiki doesn't support searching, but I think it's not that
>> important because it will contain only design documents (limited
>> life)
>
> Over the years, inability to search WILL become big pain. I am against
> anything that hasn't decent search capabilities. Our wiki on
> fedorahosted has (poor) searching, but at least there is something.
>
> You can always use Google, but points down.

In my proposal Github wiki is not meant for long-lived documents, no 
need for search. For Yard greping the source code or build-in search in 
Yard server can be used.

>> - Github wiki is backed by git, it can be cloned and modified locally
>>    - preview the changes with Gollum [1]
>
> I do not want to install, maintain and run any kind of software to write
> one sentence in the documentation. This is too painful, things tend to
> break. You say wiki pages on github supports the edit button, cool, but
> can I do the dame with YARD documentation bellow? I don't think so.
> Anyway no new punk software on my laptop, please.

I think this was misunderstood. You can always edit wiki on Github. 
Cloning and Gollum is entirely optional. I've mentioned because somebody 
may prefer it.

Editing of Yard documentation would go like this:
- change the code documentation in .rb file or some guide in .md file
   - all part of the Katello repository
- go to localhost/katello-doc/ to see the changes (hit reload in a browser)
   - katello server in development mode has to be running
- if you are happy with the result commit the changes

I think that is very simple and you do not need to do anything for that, 
see my comment about Yard server 2 paragraphs down.

>
>>    - when design is implemented page can (and should) be moved to
>> source code and serve as base for documenting the implemented design
>
> That is not a valid argument. We are going to split our git codebase
> into small repos in future (katello-configure, katello-agent,
> katello-server). At the end of the day, documentation would end up in
> a different repository perhaps. Logically, it seems to be nice to have
> docs and code together, but practically there is no added value.

I am not getting why does splitting in the future matter? As you said 
documentation would only end up in different repos, I do not see any 
problem. See my general comments about why I think that having docs and 
code together does matter.

>> - yard server (serving the documentation) would be part of Katello server
>>    - monitors file changes and re-renders documentation
>>    - documentation at hand
>>    - only in development mode
>
> No more yet-another punk software on my laptop please. Why would we
> maintain another stack when we can generate html "javadocs" during build
> time. Our users and customers do not need javadocs in the katello UI.
> I don't see the point.

A developer would get this for free. I already have working prototype on 
my machine. This is intended only for Katello in development. When 
Katello server is running in development mode, documentation will be 
made available by the same server. Its just another Rack application in 
the same Ruby process. It does not introduce another dependency and once 
its merged nobody has to do anything, it just works.

>> - written in markdown
>
> Mark down is like Puppet. Awesome idea, but with poor implementation. So
> many markdown libraries suck. We already have the redcarpet in our
> codebase which is causing various pains when I try to start development
> mode on a production machine.

May be we could switch to other markdown implementation to avoid the 
trouble. There is a lot of them 
https://www.ruby-toolbox.com/categories/markup_processors. I think 
kramdown could be a good choice.

>> - yard generates static html or the documentation can be served with
>> yard server
>>    - so it can be placed to Github pages as static html
>>    - or pushed regularly to Heroku where yard-server would be running
>>      - when served with yard-server, search field is available
>
> Anything can be set up as static html pages, this or that.
>
> Petr, I very much appreciate your effort in getting nicer documentation.
> Kudos. But I would rather stick with more reasonable things. Wiki does
> not hurt, it is working for many years and it will be here perhaps
> forever. Learning ratio is much higher than markdown/yard. And I cannot
> say those two things will not be replaced with Ruby 2.2.

The future may be uncertain but it will be here for few years and I 
think week-or-two-long-afford to get the benefits for few years is worth 
it. Otherwise we could wait for a stable solution for ever, in Ruby 
world in particular.

> My counter proposal:
>
> - let's stick with fedorahosted wiki for design documents and community
>    documentation
>
> - you would transfer the two design documents you already wrote from
>    yaml format to the wiki

I've already done that, until this is decided copy of the documents is 
placed on wiki not to introduce any other place for documentation.

> - let's document our code with simplest possible solution (plain text or
>    yard) and let's create katello-doc package that would have this
>    codebase documentation generated as text and html (I think we have
>    already made the decision about tool for documenting the code - partha
>    did the research and, correct me if I am wrong, yard was the winner)

Ifaik Yard is the only Ruby general documentation-tool (similar to 
sphinx). There are more tools for only code documentation but I thing 
that is not enough.

Petr

> LZ
>