Navigable website

[yellowbrickc]

Hi everybody,

in order to have a better user experience when navigating through all the knowledge collected in these 10 or 11 repositories, Kenny, Nick and I discussed that a simple way of using GitHub-pages would be a good start.

I created one main repo for the homepage and configured the pages in 2 other repositories (listed on the homepage)

Next harder question is: which theme to use??
For the homepage and the eventstorming repo I used the theme "minimal", for the starter-modelling-process the theme "architect". But there are several others for free.

Here you can see, which themes are available and also how to configure them https://docs.github.com/en/github/working-with-github-pages/adding-a-theme-to-your-github-pages-site-with-the-theme-chooser You can also try them out in the repos (just please change it back after you are done so that others have the same start 😉 )

If anybody has other ideas, he/she is very welcome of course. Setting up github pages takes 2 minutes/repository so this is my preferred way for the moment 🙂

[NTCoding]

I'm a bit of a minimalist so that gets my vote.

[skleanthous]

Ime, github pages are really easy to work with and require minimal knowledge to start using. The author side of things is quite pleasant too, so I think overall it's a good idea, but it is quite minimal indeed.

The two most important bits that is somewhat lacking is search, and more advanced navigation capabilities (tags, categories, etc). I don't know if this is really a concern, but I found static page tools like Hugo to be a really good compromise between authoring experience and consuming experience. Specifically, for documentation pages I've used the learn hugo theme and I've been quite happy with it.

This is a tradeoff between authoring experience and reading experience, so I'm not suggesting doing this, but ime it does make the consuming information and searching experience noticably better, so I'm just offering it for consideration.

[skleanthous]

I would be happy to setup an example using netlify if you're interested in something like this.

[yellowbrickc]

Yes, please! You can use any repo, the pages are not common knowledge yet.

[skleanthous]

Hello, and sorry for the time taken a bit to come back about this.

You can browse an example site here: https://goofy-dijkstra-40440d.netlify.app/ This is automatically published from my fork of the starter process repo currently.

As I said above, this has a couple of characteristics which may be beneficial:

1. Integrated search, which can very easily be enhanced as a one-time effort using the free algolia tier
2. Directory structure, and automated build-time table of content etc
3. Tagging of entries, which can be used to later retrieve information

However, while doing it I realised a couple of things:

1. It's not just plain md files, which will probably negatively influence contributions. This wasn't something that I've considered earlier. This could be solved, but it's a significant amount of work
2. It requires hugo in order to run the site locally. This isn't THAT big of a problem since it's the same as Jekyll, but still is somewhat of a problem because you could easily observe if things worked through a PR with normal md files in a repo

After doing this, I'm not too sure what I'd recommend for moving forward. Personally I feel that advanced search is really important for information which is more than 2-3 pages long, but if this even slightly inhibits contributions I'm hesitant to agree with proceeding with this. What are your opinions?

[skleanthous]

cc @yellowbrickc & @NTCoding

Btw, the repository where the build is running from is here: https://github.com/skleanthous/ddd-starter-modelling-process

All information and pages are in the content folder, and that's the structure which has to be followed.

[skleanthous]

I forgot to mention, that I did a bit of work too on the possibility of using separate repos with plain md files. What that would require is the following:

1. A repository which would act as an entry point (basically this: https://github.com/ddd-crew/ddd-crew.github.io) and which will include links to all the other GitHub pages.
2. Search which works dynamically by periodically crawling a site and indexing it. Algolia can do this too, but such capabilities would require a bit of work to set up, and don't usually come in free tiers.

That ☝️, while it allows to use the existing information and keep the structure, has the drawback that the directories and links to different repos would have to be manually maintained, which is not the case in Hugo. When documentation becomes large enough, this becomes quite important, and it's not something which can be fixed easilly.

Anyway, regardless of the approach we'll take, I hope that I at least helped people make a more informed decision

[yellowbrickc]

Anyway, regardless of the approach we'll take, I hope that I at least helped people make a more informed decision
Absolutely! Thank you for the detailed analysis of the possibility we have!

This is the question, what effort do we want and are we able to invest? After the last months, I would say, we don't want to spend time on maintaining a separate site. Plus: we don't even know if it is it needed. This was my main motivation to invest the minimum and afterwards ask the community if it is needed, it is enough, would be important to have more features, only search or other stuff too?

I agree that the search would be important but at the moment we have nothing To be honest, I don't have a plan if we found out that search is a must-have but I would say, let's worry when we are there 🙂

@Baasie has already included the content to https://virtualddd.com/learning-ddd and he forks the repos to render them in the site but I have no idea if it is used or not. The question is also still valid: do we really need this navigability?
My answer is: an instant decision about the design and publishing the sites. The costs are around 30 minutes and after that we will know more than now.

[skleanthous]

It really depends. People may not even be aware that there are other repositories with (potentially useful) information. Imho, we should have some form of directory accessible from a homepage-like page for discoverability purposes.

I believe this is exactly the reason which makes the ddd starter process repo so successful: it is quite comprehensive and acts as a directory of information. We could structure that page around the ddd starter process repo, but will everything be linking from there?

And then again, as we add new repos, or stuff that we want to link to, we'll need to maintain it.

[yellowbrickc]

We could structure that page around the ddd starter process repo, but will everything be linking from there?
I had the same question some time ago 🙂 #15

For the start, I created the "cover page" https://ddd-crew.github.io/ and added all supported sites. This is not really an effort.

[yellowbrickc]

Current state: if we succeed to deploy from all repos to the same target (the ddd-crew.github.io) then we can use different plugins to search through the content. I opened a topic in the bithub-community, let's wait a few days before we make the next step.

It would be still very important to know if the ddd-crew-pages are used @Baasie . Do you have any idea?

[skleanthous]

One way to do this would be to have the central add the others as submodules and have a watcher service re-building everything on a periodical basis (every half-hour or so) to pull in new commits.

Also, I was changing hugo for our internal documentation site, and it can be made to work without front matter quite nicely, so long as a directory can be maintained in the main repo. This would allow something like algolia to be used for searching and be pretty low maintenance too, but does require 2-3 full days of up-front effort. After that the only time this will need to change is when a new repo is added, or if we want to make a change in the website for some reason.

[yellowbrickc]

Sorry for the silence, I had to take some time off from digital stuff :)

These are really good news, I think. I would volunteer for the submodules. Would you take over the hugo/algolia part?

[Baasie]

Hi,

I was on holiday for a while. As @yellowbrickc mentioned, on virtualddd.com/learning you can also find the ddd-crew repo's. Here you see the last month statistics of the use:

ASs you see it is being used and also I have build in SEO and stuff so people can easily navigate and find it :)