Website structure

A the moment we have the following structure:

• Homepage: 2 paragraphs PROTEIN STRUCTURE MODULES and BIOLOGICAL SEQUENCES; addresses to mailing lists; a link to the tutorial; a link to the API; a broken link to the cookbook;
• A link to a unstructured and outdated wiki I suggest to host on GitHub wiki and not on the website.
• A lot of example pages of the Spectral Jekyll template I suggest to remove because it is no productive content. We can describe thinks like that in the wiki.

My questions is what content and structure we want to achieve on the website?

Maybe we can collect some ideas and rewrite the website to a modern, well structured and informative one which can show the serious and high quality character of the project.

My idea is to have a simple one page responsive website with the following information users and devs needs:

• GitHub link
• (GitHub) wiki link
• Table of current and maybe older versions with link to API
• Introduction; Features; Minimum requirements; Quick Start (maven/gralde dependency) and some cool minimalistic examples how easy and powerful biojava is.
• Link to a tutorial
• Maybe link to a video tutorial or at leas an introduction
• Some polished stock photos like this one.
• Maybe a link to a blog/twitter (everyone loves news)
• Asking for help - a link to tagged stackoverflow where users can talk about how to use the lib.
• Links to companies/projects already uses biojava

I would not to store information for developers on the website. The right place for it is the README.md file of the project repository.

That is.

What do you think? Any ideas?

[andreasprlic]

So, we actually do have a lot of content as part of the wiki pages. Trying to squeeze it all on one page might be challenging. I think we could have several "chapters" that contain a collection of more detailed pages for various topics. Topics that come to my mind are:

• pages for contributors (coding standards, how to commit, how to discuss changes)
• pages for users (how to get a copy of the code, where to find documentation, how to set up IDEs, where to provide a bug report)
• cookbook pages
• about (who we are, developer pages, student projects)

Yes, there is a lot of content on the wiki pages and probably there will be even more in the future. This is too much content to place on a single webpage. Thats why I suggest to use the GitHub wiki as a right place for this content instead of putting it on the website.

Here are some examples of GitHub wikis:

• https://github.com/guard/guard/wiki
• https://github.com/Netflix/Hystrix/wiki

Using of the GitHub wiki has a lot of advantages:

• Using GitHub as a platform not only for hosting the git repository but also as a integrated information platform about the project itself
• Using the GitHub markdown and linking between pages
• Nice code snippet highlighting
• Handling the wiki as a separate git repository

What do you thing? Should we change to GitHub wiki or leave the wiki on the website?

[andreasprlic]

That would work for me. GitHub wikis are also git repos by themselves. That should make bulk import or export easy. (Export is important because history suggests that every few years we migrate hosting of our content to a different platform so we need to avoid vendor lock-in.)

Great. GitHub is actually a very good choice because the project is hosted anyway on it. So there will not be a vendor lock-in.

Maybe I begin to general structure the wiki and migrate the content. Please let me know if you have a different opinion about the structure.

Here is the link to it:
https://github.com/rmoszczynski/biojava/wiki

As soon we have a first usable version we can merge it to the main project.

[sbliven]

@rmoszczynski The wiki you started looks good.

I'm still unclear what the advantages of a github wiki are over a github page. They're both markdown documents. I guess the barrier to entry is lower for wiki pages due to the prominent edit button and the github header & styling. The full site requires a PR for changes, but gives us full control over the styling.

Does it make sense to have both? If so, how would we split content between them?

@sbliven

The main advantage is to store the information on a system that is made for storing the type of content and there where the most devs/users expect to find the information. GitHub wiki is just build for a wiki.

The GitHub wiki looks great, offers functionality like linking of pages in the sidebar menu, supports markdown (and other dialects), a nice syntax highlighting and last but not least stores the files as a separate git repository (https://github.com/rmoszczynski/biojava.wiki.git).

If you compare the two websites:

• http://biojava.org/wiki.html
• https://github.com/rmoszczynski/biojava/wiki

What do you feel is a better fit to store a wiki for a project?

To use a GitHub wiki is only my suggestion before I start to improve the website. Thats why I build a minimal wiki to show how such wiki works and looks. Maybe thats make a better base to the decision if we want to use the website or GitHub wiki for the project wiki.

I would suggest to use the website only for minimal information purposes, provide a great look, a general project description with features and a buch of links I suggested in the first comment of the topic.

What is your opinion about that?

Here a next suggestion on how to structure the content.

StackOverflow is #1 place where devs and users looking for help. This is also a great opportunity to build a community. It's also a platform for high quality Q&A content - what a Cookbook actually is - a collection of receipts. Last time StackOverflow roll out a new great feature: Documentation. Here is the link: http://stackoverflow.com/documentation.

Providing the Cookbook on StackOverflow Documentation has a lot of advantages and could be a boost for the BioJava project.

What do you think? Should we build the Cookbook on StackOverflow Documentation?

[andreasprlic]

Hi,

So there are a couple of forums where people post bioinformatics related questions:

• https://www.biostars.org/t/biojava/
• http://stackoverflow.com/search?tab=newest&q=biojava
• http://biology.stackexchange.com/questions/tagged/pdb

to mention just a few of them. I'd rather not rely on an external site for hosting our content, but try to keep everything under the GitHub umbrella. The cookbook was also a wiki on the previous site (before we moved to github pages). Moving them to Github wiki might the natural thing to do now.

I like what you started to do on your own github wiki !

OK @andreasprlic, thank you for your opinion. To keep the content on the GitHub umbrella is a good decision I think. We can put additional content on StackOverflow Documentation if we want to later.

So I will begin to manually transfer the content to the GitHub Wiki I started and tell you when it's ready to merge.

@andreasprlic there is one more point with the cookbook. A cookbook is a collection of recipes. Each recipe can contain not only a problem/solution text parts but also additional files, for example source files, input data etc. Thats why a recipe is more a directory as a file (page).

I would recommend to write the BioJava Wiki as a additional repository with the following structure:

The reposiotry itself: https://github.com/biojava/biojava-cookbook
The recipes directory: https://github.com/biojava/biojava-cookbook/recipes
A example recipe: https://github.com/biojava/biojava-cookbook/recipes/protein-disorder

And in each recipe at least a README.md file describing a problem/solution.

In this way we stay under the GitHub umbrella and have much more flexibility handling recipes as directories instead of Wiki pages.

Here is a great example of a project cookbook structured this way: https://github.com/reagent-project/reagent-cookbook

What do you thing about the idea?

[andreasprlic]

good point. that reminds me of our tutorial. perhaps they should get merged?

https://github.com/biojava/biojava-tutorial

In my opinion a cookbook is a set of isolated problem/solution pairs. It's not really suitable for learning a subject or giving an overview but rather for solving common problems.

A tutorial comes into play if you want to learn a subject. It is a guided proces explaining the concepts from the basic to advanced topics. That's why I think a tutorial has its own right to existence. It shows you where to begin, what problems can be solved and how and ends up with a reference to forums and the cookbook.

[sbliven]

We have a lot of example code scattered in various places: the tutorial, the old /wiki/BiojavaCookbook: pages, and the demo packages of each module.

• The tutorial is nice because it incorporates prose and has a clear flow from chapter to chapter
• The previous cookbook pages were well organized and addressed clear questions
• The demo packages don't have any prose (excepting a few comments), but they all compile with the current master

Of the three, only the demo packages have been kept up-to-date, since they break compilation if they aren't. I think this is a huge advantage, and perhaps more important than having fancy formatting and prose.

I would suggest that any new documentation system we start needs to be executed by travis against the current release, so we at least know that it is up to date.

[andreasprlic]

@rmoszczynski on this ticket we were discussing literate programming:

biojava/biojava-tutorial#13

In an ideal world we would be incorporating that into our documentation. Do you have any thoughts on that by any chance?

A

Yes, outdated documentation is a massive issue and literate programming is an option. There is for example Eclipse Intent supporting it.

Personally I have no practical experience with that. I can imagine there are some challenges applying this concept in a project. Depending of the IDE devs uses literate programming should be supported. Disadvantages and restrictions should also be clear for us. But maybe it is a good idea. We can try and evaluate this option as an separate topic. There are some issues to discuss when it comes to software quality we can apply.

I think the only places where we should write prosa about the code is the tutorial and cookbook. Independently of we decide to use litarate programming or not, the comments should be as close as possible to code. If we use the speaking code programming style (detailed and explicit) and comment why we do something and no what we win much in readability and also partially code quality.

I would suggest the following steps:

1. Start to move the suitable content to the GitHub Wiki and the cookbook the the biojava-cookbook repository. There will be content left that not fit in the Wiki or the cookbook we can discuss later what to do with it.
2. Fix the website
3. Discuss and apply important quality issues like coding convention, CI tools, tests etc.