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

Tue Nov 20 15:30:35 UTC 2012

On 20.11.12 14:19, Bryan Kearney wrote:
> On 11/20/2012 07:41 AM, Petr Chalupa wrote:
>> 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.
>>
>
> Where do general pages go which are not tied to a piece of source code?

Usually all non-tied files go into src/docs directory. Which files are 
used is configurable [1], I've used `./doc/**/*.md` to pick up any md 
(markdown) file in doc directory or sub-directory.

Files can be organized in any directory structure you see fit.

Links are created anywhere in Yard documentation with syntax 
`{file:docs/GettingStarted.md Getting Started}`, see [2] for other options.

I would spit the files in two categories:
docs/user_guides/
docs/developer_guides/

[1] 
http://rubydoc.info/docs/yard/file/docs/GettingStarted.md#Documenting_Extra_Files
[2] 
http://rubydoc.info/docs/yard/file/docs/GettingStarted.md#Linking_Files__file_____

Petr

> -- bk
>
>
> _______________________________________________
> katello-devel mailing list
> katello-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/katello-devel