seo and documenting multiple version of our software

How to markup the documentation of the different version of our product?

considering that

  • The content is not strictly identical across version,
  • but it is very often the same,
  • we wish newer version to be preferred by seo engines,
  • but older versions are preferred since they are older.

for a couple of year our strategy has been to follow this answer to the question

  • have all url prefixed by their version
  • create a “latest” prefix that is a symlink pointing to the most recent version
  • the most recent version have a <link rel="canonical" targeting the “latest”
  • all version (except the most recent) start with a disclaimer indicating that this version is not the latest, this disclaimer include a link pointing to the latest version

This is an example of our urls :

  • old version : https://www.itophub.io/wiki/page?id=2_4_0%3Auser%3Astart
  • latest version : https://www.itophub.io/wiki/page?id=latest%3Auser%3Astart
  • latest version duplicate, with the <link rel="canonical" : https://www.itophub.io/wiki/page?id=2_7_0%3Auser%3Astart

This is an example of the disclaimer including a link to the latest version picture of the link pointing to the latest version


This was meant to strengthen the “latest” url by having a stable url over time and by having several pages linking to it.

This does not seem to work, since google continues to prefer olds pages. What should we do? I only see the nuclear weapon here : adding on all version a <link rel="canonical" targeting the “latest”.

Suggestions for documenting namespaces with Doxygen

Consider several C++ classes which are all defined in a particular namespace. For cleanliness, each class is located within its own file, and are each well-documented.

For the purposes of completing the documentation with Doxygen, we’d also like to add documentation for the namespace itself.

Does anyone have any suggestions for a good best-practice solution for this? We’ve got a couple of options:

  • A dedicated namespace.h file which contains only the namespace and the documentation for it. This means there is a single location to describe the namespace, but does mean having a seemingly purposeless file.
  • Add the description for the namespace inside one of the class files (such as the most significant one?). This means not having to add a new file, but does make it harder to find the description if there ever is a need to modify it.

Addressing security issues for documenting internal systems

The Situation

I’m presently a member of a healthcare records team that is sorely understaffed and has an incredibly low bus factor, with only two people with the majority of system knowledge, myself – allocated temporarily, and a consultant – also allocated temporarily. As a result I’m aware the system must be documented or face clinical risk.

Why it’s being documented

There is an incredible amount of system sprawl, complex processes with very little documentation, and I’ve taken it upon myself to start documenting the internal systems (including IPs, ports and database names, but no usernames, passwords or personally identifiable information) on an internal Wiki which the entire organisation can view (which if kept behind a username/password, might be lost in the event of either or both of us leaving).

The issue

The consultant has reasonably raised that they are not comfortable with the idea of IPs and ports for databases etc being found in a central location accessible by the entire organisation.

Whilst I acknowledge that could be useful information for an attacker, my counter-argument is a simple IP and port scan would reveal the same information (if not more), that no usernames or passwords are included on the Wiki, and if they can get in with an IP/port, then that process wasn’t secure to begin with.

My greater concern, on balance of best interests, is to document the system in a transparent manner such the organisation is able to train replacements, which otherwise, if left undocumented, could become an unmaintainable mess and cause all sorts of clinical risks and issues.

The question

Is the approach I’m using for the current situation the correct approach security wise, or is there a better way of handling it?

[It’s worth noting this organisation has no coherent usable system of documentation of available skills, knowledge etc with similar situations in other departments, and I’m trying to encourage an organisation-wide adoption of a Wiki to help mitigate this problem.]

Documenting business logics of legacy application having no unit test

I have joined a team in company and this team owns few services, which are used widely by many other user facing internal/external UI apps and other internal apis.

My manager gave me rough idea that these services are responsible for, let’s assume, around $ 1B worth of traffic, or something like, so idea was, it’s super critical.

There are tons of business logic, lots of if/else in c# code. Also sql Stored procedures and sql function are used. I have worked in these kind of code in past also, so I know these services are complicated too.

System mainly in maintenance mode, so no frequent code changes.

There are no unit tests and very minimum documentation.

There is an effort going on to rewrite these services side by side, without modifying this existing, and some migration plan. My manager want me to understand business.

Need for frequent releases, data issues in this monolithic in various environment, old infrastructure and high maintenance causing money, are few reasons. There is an initiative for cloud Native microservices in my organization.

In past, for these kind of scenario, I wrote integration test first. But this time I am trying to write this in BDD style, not sure if this going to be a right approach. I never worked with BDD, but read about it. Seems output of BDD is good documentation, with other benefits. Nevertheless my ultimate aim to document business logics so that we can use it while rewriting this application. Refactoring seems not an option here.

Suggest me if I am going in right direction, any other points I should take care of, on effective documentation of business logics.

What is a good method/practice I can employ to keep identical code snippits in two places in sync? Also, help documenting functionals

If I could get some input on the design of this, I would be grateful as well.

Note that I’m programming in python.

There’s a function F that takes lots of data, runs some analysis on it (taking maybe a minute or more) to compute some crucial fruits theta, and then spits out a function g(x), that has a lot of functionality that it can do efficiently solely by accessing theta, the fruits of analyzing the data.

Now one might wish to save this g function. So I designed the following functionality

theta = g(mode="get theta") # gets the `theta` value that `g` was using # perhaps store `theta` as a pickle file, or a json file, whatever # read `theta` from its storage restored_g = restore_g(theta) # restore_g is a function that                                # takes a `theta` and gives you                                # a `g` that runs based off that                                # `theta` 

If you want a concrete example to think about, think interploation. F gets a bunch of data points, and after processing, spits out an interpolation function g. You can’t save a function though, so you save the theta that g was using, and then you can theoretically restore the interpolator later on with a restore_g function using that saved theta.

The thing is, though, that the code for F and restore_g will look like this

def F(data):   theta = do_tons_of_processing(data)   def g(args):     return do_stuff(args, theta)   return g  def restore_g(theta):   def g(args):     return do_stuff(args, theta)   return g 

The problem here is that

def g(args):   return do_stuff(args, theta) 

appears twice, exactly the same, seemingly by necessity. I can’t think of a way around editing that snippet of code in both places whenever I want to make a change to g, like what arguments it takes, the description of what it does, etc. How can I best address this?

Two more related questions I have are: what is the best practice for describing the functions?

Normally, one would do something like

def f(x):   """concise description    longer description    inputs   ------   x : int     what the input means    returns   -------   y : float     what the return value is    maybe some examples   """   return 0.2*x 

But my F and restore_g themselves return a function g, whose inputs and outputs should also be described. So where should this description happen? And how can it be maximally synced between F and restore_g with minimal redundancy?

Finally, what is the “best” (or at least, a good) practice for going about g having multiple orthogonal purposes? Sometimes, it might take an x and a y array as arguments to spit out something. Sometimes it could just take an x value to spit out something. And sometimes, it’ll take "get theta" so it knows to spit out theta. Is it considered inappropriate to just overload the x argument so that if it’s fed "get theta" (or some other keyword), then g will follow the “get theta” functionality? Is it better to create a whole other argument called mode or some such that can be set to "get theta" or what have you?

documenting a web app [duplicate]

This question already has an answer here:

  • Are there any useful tools / techniques for creating website content inventories? [closed] 1 answer

My company is trying to improve the UX in our system. It’s web based app, full with features.

The system development started 8 years ago, but it was never documented, and our programmers/support team can’t remember every small thing about the features, that causes our clients who need support to wait while we dig into the source code to find things.

We want to document it, first for ourselves but later to publish some parts of it to our clients.

Since it’s a big app, going through everything without a system/app could take forever and we probably won’t be able to cover everything.

I was wondering if anyone knows about such system/app?

I need it to be easy to use for out support/sales teams and for the users but also efficient for the documenting process.