Skip to content

Revise Documentation

Jump to bottom
Prasad Talasila edited this page Nov 10, 2024 · 33 revisions

Inspirations

codimd, ubuntu desktop install

Nick Battle

Keep thinking about that smart guy who doesn't know much, but has to use this site to get up and running. Make your user's lives as simple as possible. If we can keep him happy, we've done a good job :-)

Based on feedback from Nick Battle

Done

  1. On the main page, when you describe Build and Use, you say "the DTs". It's a small point, but by using "the" definite article, you make the reader wonder which DTs are being referred to. I know it's obvious, but this is the front page, so we want the flow to be as easy and natural as possible. I would recommend "Build: DTs are built on the software platform using the reusable DT components available on the platform." and "Use: Run your DTs on the software platform" and "Share: Read-to-use DTs can be shared with other users. It is also possible to share the services offered by one DT with other users." (made the correction)
  2. The "Next" button on the Home page is labelled "Overview" though it moves to the "Admin" tab, which starts with an overview of how to install DTaaS. It might be clearer to label this tab/next as "Install"? It's useful to have a real overview of the software early in the flow though. There is such a thing, but that is under "User". So to me, "Admin" is really "Install" and "User" is mostly "Overview", though mixed with some real usage instructions. Try to keep these clear and separate. (Rearranged the menu to have user documentation come before admin documentation)
  3. The Admin/Guide entries for creating users and services are labelled "New User" and "New Service". With users especially, this implies the section would be useful to someone new to the platform - a new user. Perhaps it's clearer to call these two "Add User" and "Add Service"? (Done)
  4. With the FAQ, it's great to see that you've added a lot of my suggestions to clarify what it can/can't do. But if you want to contrast what it does and doesn't do in one FAQ entry, it's best to say what it can/does do first and then add a "however, note that..." afterwards. If you put the negative first, it makes it read in a "mostly negative" sense, which isn't encouraging for people :-) (positive and negative points split into two questions)
  5. In the FAQ sections, try to put the basic questions at the top of the section and the more complicated ones lower down. For example in the Communications section, the last question about protocols should be first and the first, which is a more complex point about usage, would go lower. (questions have been rearranged on FAQ page)
  6. I don't think the Key Performance Indicators FAQ entry are really performance indicators; they are minimum or typical system requirements? (removed)
  7. I was expecting the Bugs page to have a link to a system where, as a user, I could raise a new bug - like the GitHub issues, if that is what you want Users to do. But there isn't one. So how do users raise bugs? (added a link to issues page)
  8. I tried playing with the search function, which is quite strange. I tried looking for the "Yes, you are right" FAQ answer, but it seems to have problems with multi-word queries. Are there any search settings that can improve this? (unfortunately not. The search function is based on lunrjs which can only do single word search)
  9. The licensing FAQ entry says, "The licensed software are not available on the software platform". Not sure what this means. It definitely should be "Licensed software is not..." but you have also said that it uses open source licensed software elsewhere. Perhaps you are talking about proprietary licences? Anyway... needs correcting and clarifying. (sentence rewritten)
  10. The "Developer" tab says "This guide is to help developers get familiar with the project." I think you are talking about developers working on the DTaaS project itself as opposed to users of the platform? That's Okay, but it may be a little confusing to mix the two at the top level. Perhaps consider moving "Developer" under the "Bugs", to make it clear that you're aiming at developers who work on DTaaS related software, not developers who work with DT models. (rewritten those sentences to identify the target audience)
  11. Make a clear difference between Admin/Install, User/Overview and Developers/Bugs information. (rearranged and renamed the structure of help pages)
  12. The FAQ entry that says, "Yes, you are right" is inverted (the answer is the question) :-) Given the other FAQ answers, I'm not sure this one adds much? (question and answer have been rewritten)

TODO

Developer Notes

Make the installation work for basepath and different ports.

add notes of E2E testing setup (under developer documentation)

Documentation

  User
  Examples
    DevOps examples + GUI examples + MQTT from CPSENS

  Admin
    Cookbook
      Use of code in ssl/ for installation with self-signed certificates. Compare with mk-cert

  FAQ
    - user: download directory from jupyter 
        - notebook
          https://cacarer.com/tip/downloading-all-files-in-a-directory-from-a-jupyter-notebook-server/
        - lab
          https://stackoverflow.com/questions/61710897/downloads-folder-from-jupyterlab
          https://stackoverflow.com/questions/43042793/download-all-files-in-a-path-on-jupyter-notebook-server
Clone this wiki locally