Closed SergeHendrickx closed 2 years ago
Is there any specific reason why it is currently not set-up like this?
It's something I struggled with when setting up the documentation, since I wanted to use BookStack for it; but the reality was that a static site generator suited much better for the management I intended for the BookStack docs.
In my opinion BookStack works best in a multi-user environment where easy-access/edit-ability and interaction of "live" documentation is desired. For the docs, it's mainly me editing with a requirement for a controlled process for others to contribute where desired. In addition I have to prepare many changes ahead-of-time synced with the website and blog to deploy at release time. Editing by non-technical people is not really a concern either.
The reality is that having all the site, blog and docs in one repo built via a static site generator works really well for this specific use-case and scenario, and does not play to the strengths of BookStack itself.
While some may view it a hypocritical, documentation as a general term/requirement/idea is extraordinarily wide. There are different solutions that have different strengths for different situations and requirements. A "internal company documentation" use-case will be vastly different to "external product documentation". BookStack itself is quite opinionated and was built for a general use-case quite different to that of our docs, It's never intended to be a system that covers any use-case related to documentation.
While I could put the docs into a BookStack instance (And I'm sure it'd do a functionally serviceable job), I don't think it would showcase the platform in an ideal way and could misguide people on its intended usage.
Thanks for the detailed reply. I fully understand your point of view. And to be clear, I definitely don't want to force you to make any changes in this process, just sharing some thoughts.
Maybe the points you just made could be seen as a list of potential improvements/changes for Bookstack. These points are your answer to the question "What is holding me back from implementing Bookstack in my environment?" And those points could also be exactly what is holding back other users/customers from implementing Bookstack.
it's mainly me editing with a requirement for a controlled process for others to contribute where desired.
True. But you never know... maybe that would change once people can easily make changes in a simple WYSISYG interface with easy login using github Oauth... Or if ever there will be 3rd party integrations with custom external add-ons, plugins, themes.... Information from those could be added easily to the wiki by the 3rd party devs for example.
In addition I have to prepare many changes ahead-of-time synced with the website and blog to deploy at release time.
I was thinking if a wiki-wide versioning is something that would make sense to implement? Like docosaurus has for example in the top-right.
I think you have a much better view on the wiki-ecosystem and whether or not that is something that would also be useful outside of code-docs. I expect this kind of change to have a very big impact on the code-base or database structure so I'm not expecting any quick-decisions here of course.
In general, while I definitely understand your reasoning and arguments, the fact that the "one on the right" does not fit into the framework of the "one on the left" in the screenshot below feels a bit wrong. Because they look so similar.
Congratz on everything you've done so far with the application by the way! I really like the interface and the concepts behind the app. I've been playing around with it today and everything went pretty smoothly.
Maybe the points you just made could be seen as a list of potential improvements/changes for Bookstack. These points are your answer to the question "What is holding me back from implementing Bookstack in my environment?" And those points could also be exactly what is holding back other users/customers from implementing Bookstack.
Sure, but I don't really believe in this approach in this case. The focus is to make BookStack the best for its current use-cases, not widen the scope to other use-cases, especially with a narrow focus on my usage for the docs, since this can lead to blurry vision and a weaker result for its core user-base. Many features and ideas have been put forward with a justification of a wider audience and suitability of more use-cases but from my experience over the last 7 years that takes us towards a harder to maintain & progress project while moving towards being a more generic platform.
In general, while I definitely understand your reasoning and arguments, the fact that the "one on the right" does not fit into the framework of the "one on the left" in the screenshot below feels a bit wrong.
I did not say this. The doc content & structure could fit into a BookStack instance fairly well but I don't think it would provide a good show-case of an instance of the platform, while the use-cases and processes desired for the site and docs play better to a static-site-generator.
Congratz on everything you've done so far with the application by the way! I really like the interface and the concepts behind the app. I've been playing around with it today and everything went pretty smoothly.
Thanks, good to hear! I think the original question has been adequately answered across these two responses so I'll therefore close this off.
There are some significant ideas about bookstack in this thread that I've not encountered (or recognised) in my reading so far. I think they could-should be folded into the project description. For me the insight here is: Bookstack is not a generic CMS, and doesn't want to be. It's not trying to be Wordpress, but different. It is for documentation, for books (duh!), and multiple authors. Although it can be used to build a the website du jour, for blogs, a portfolio,.. and do a good job if wielded right, those aren't the target domain. The word 'opinionated' in the front page is doing a lot of heavy lifting and there would be benefit in unfolding it.
Or not. I drafted a few options but couln't fit them anywhere. Maybe this thread is enough. ;-)
Describe the feature you'd like
The official documentation on https://www.bookstackapp.com/docs/ is currently not hosted using a Bookstack instance. In my opinion this could be a great showcase of a Bookstack instance running in production. While browsing the documentation on the website, I suddenly got a strong "Wait a minute, this interface looks like bookstack.... But I don't think it actually is Bookstack"-feeling.
Is there any specific reason why it is currently not set-up like this? The best way of showing confidence in your product is by using it yourself I would think....
Describe the benefits this would bring to existing BookStack users
Have an online example of a Bookstack-instance with actual data to see how it could look like in a real production environment.
Can the goal of this request already be achieved via other means?
There is the online-demo, which is very good and I would definitely keep that.
Have you searched for an existing open/closed issue?
How long have you been using BookStack?
0 to 6 months
Additional context
No response